ATOM Documentation

Gap Analysis: Atom SaaS vs Open Source (Single Tenant & Self-Hosting)

**Date:** March 31, 2026

**Purpose:** Identify gaps between the main Atom SaaS repository and the open-source atom-upstream submodule for single-tenant and self-hosting capabilities.

---

Executive Summary

The **atom-upstream** submodule is a fully-featured **single-tenant, self-hosted** platform designed for personal and enterprise self-deployment. The **main repository (backend-saas)** extends this with comprehensive **multi-tenant SaaS** capabilities including billing, subscription management, tenant isolation, and enterprise governance.

Key Findings

---

1. Architecture Comparison

1.1 Tenancy Model

atom-upstream (Open Source)

┌─────────────────────────────────────┐
│     Single Tenant Instance          │
│  ┌───────────────────────────────┐  │
│  │  All Data → Single Database   │  │
│  │  - No tenant_id filtering     │  │
│  │  - No RLS policies            │  │
│  │  - No tenant isolation        │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

**Characteristics:**

• Explicitly **single-tenant** architecture
• All tenant_id columns removed from schema
• No Row-Level Security (RLS)
• No tenant isolation enforcement
• get_current_tenant() returns synthetic tenant for localhost

Main Repo (SaaS)

┌─────────────────────────────────────────────────────┐
│              Multi-Tenant Platform                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │  Tenant A   │  │  Tenant B   │  │  Tenant C   │ │
│  │  ┌───────┐  │  │  ┌───────┐  │  │  ┌───────┐  │ │
│  │  │ RLS   │  │  │  │ RLS   │  │  │  │ RLS   │  │ │
│  │  │ Data  │  │  │  │ Data  │  │  │  │ Data  │  │ │
│  │  └───────┘  │  │  └───────┘  │  │  └───────┘  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────┘

**Characteristics:**

• **Multi-tenant** with database-level isolation
• Row-Level Security (RLS) on 9+ tables
• tenant_id filtering on all queries
• Subdomain-based tenant routing
• Custom domain support

**Gap Analysis:** ✅ **Intentional** - SaaS features not needed for self-hosting

---

1.2 Database Architecture

**Gap Analysis:** ✅ **Intentional** - RLS and tenant isolation are SaaS-specific

---

2. Self-Hosting Capabilities

2.1 Deployment Options

atom-upstream (Excellent Self-Hosting)

**Key Features:**

• 5-minute setup for Personal Edition
• Comprehensive .env.example with 19 sections
• Health checks on all services
• Non-root users for security
• Volume persistence
• Backup automation scripts

Main Repo (SaaS-Focused)

**Gap Analysis:** ⚠️ **CRITICAL GAP** - Main repo lacks comprehensive self-hosting options

---

2.2 Docker Configuration Comparison

atom-upstream Docker Compose (Personal Edition)

# Complete stack with 4 services
services:
  atom-backend:    # FastAPI with hot reload
  valkey:          # Redis-compatible cache
  atom-frontend:   # Next.js dev server
  browser-node:    # Browser automation

**Features:**

• Hot reload for development
• Health checks on all services
• Volume persistence (./data)
• Network isolation
• Local-only mode (ATOM_LOCAL_ONLY=true)
• 46+ integration credentials pre-configured

Main Repo Docker Compose

# Basic 3-service stack
services:
  db:      # PostgreSQL
  redis:   # Redis
  api:     # FastAPI

**Missing:**

• ❌ Frontend service
• ❌ Browser automation
• ❌ Health checks (minimal)
• ❌ Development mode
• ❌ Volume persistence (basic only)
• ❌ Integration credentials
• ❌ Monitoring stack

**Gap Analysis:** ⚠️ **SIGNIFICANT GAP** - Main repo Docker setup is incomplete

---

2.3 Environment Configuration

atom-upstream `.env.example` (323 lines)

**Sections:**

1. Core Configuration (NODE_ENV, LOG_LEVEL)
2. Database & Storage (SQLite/PostgreSQL)
3. Authentication & Security (REQUIRED keys)
4. AI Service Credentials (BYOK - 5 providers)
5. Communication Integrations (6 platforms)
6. Google Services (OAuth)
7. Project Management (6 tools)
8. CRM Integrations (3 platforms)
9. Storage & Cloud (5 providers)
10. Smart Home (4 platforms)
11. Media & Entertainment (3 platforms)
12. Development & DevOps (4 tools)
13. Finance & Accounting (4 platforms)
14. Customer Support (3 platforms)
15. HR & Recruitment (2 platforms)
16. Marketing & SEO (3 platforms)
17. Security & Compliance (2 tools)
18. Analytics & BI (2 platforms)
19. Other Integrations (5+ platforms)

**Total:** 46+ integration providers documented

Main Repo `.env.example` (237 lines)

**Sections:**

1. Core Platform (basic)
2. Billing (Stripe)
3. Email (SendGrid/SES)
4. AWS Services
5. CRM Integrations (3)
6. Communication (partial)

**Missing:**

• ❌ AI provider credentials (OpenAI, Anthropic, etc.)
• ❌ Most integration credentials
• ❌ Smart home integrations
• ❌ Media integrations
• ❌ Development tools
• ❌ Finance platforms
• ❌ Customer support tools
• ❌ HR platforms
• ❌ Marketing tools
• ❌ Security tools
• ❌ Analytics platforms

**Gap Analysis:** ⚠️ **CRITICAL GAP** - Main repo missing 70% of integration documentation

---

2.4 Deployment Scripts

atom-upstream Scripts

Main Repo Scripts

**Missing:**

• ❌ Production setup automation
• ❌ Deployment orchestration
• ❌ Backup automation
• ❌ Monitoring setup
• ❌ Native installation
• ❌ One-command start

**Gap Analysis:** ⚠️ **CRITICAL GAP** - Main repo lacks production deployment tooling

---

3. Multi-Tenancy Features (SaaS-Only)

3.1 Tenant Management

**Main Repo Only:**

• ✅ Tenant model with subdomain/custom domain
• ✅ Edition system (personal/enterprise)
• ✅ Plan types (free, solo, team, enterprise)
• ✅ Quota tracking (memory, agents, budget)
• ✅ Trial management
• ✅ BYOK support (ai_mode: byok/managed/hybrid)
• ✅ Tenant settings (key-value store)
• ✅ Workspace isolation

**atom-upstream:** ❌ None (single-tenant by design)

**Gap Analysis:** ✅ **Intentional** - SaaS features not needed for self-hosting

---

3.2 Billing & Subscription

**Main Repo Only:**

**Billing Routes:**

• /billing/status - Budget usage
• /billing/forecast - Month-end forecast
• /billing/admin/report-usage - Stripe reporting
• /api/admin/usage/* - ACU usage dashboard

**atom-upstream:** ❌ None (no billing for self-hosted)

**Gap Analysis:** ✅ **Intentional** - Billing is SaaS-only

---

3.3 Security & Isolation

Main Repo (Multi-Tenant)

**Database-Level:**

-- Row-Level Security on 9+ tables
CREATE POLICY tenant_isolation ON agents
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

**Application-Level:**

• TenantService with 4-tier resolution (header → JWT → subdomain → user)
• tenant_id filtering on all queries
• TenantIsolationError exceptions
• Audit logging with tenant context

**Infrastructure:**

• S3 prefix isolation (s3://atom-saas/{tenant_id}/)
• Redis namespace separation (tenant:{tenant_id}:...)
• LanceDB data isolation per tenant

atom-upstream (Single-Tenant)

**Security:**

• Fernet encryption for sensitive data
• Secrets migration (plaintext → encrypted)
• Per-user credential encryption
• Audit logging (single tenant)
• Rate limiting (configurable)

**No tenant isolation:**

• No tenant_id columns
• No RLS policies
• No tenant context extraction

**Gap Analysis:** ✅ **Intentional** - Different security models

---

4. Documentation Comparison

4.1 Self-Hosting Documentation

atom-upstream (Comprehensive)

Main Repo (SaaS-Focused)

**Missing:**

• ❌ Self-hosting installation guide
• ❌ Docker Compose deployment guide
• ❌ Native installation guide
• ❌ Cloud deployment (non-ATOM Cloud)
• ❌ Backup/recovery procedures
• ❌ Environment configuration guide

**Gap Analysis:** ⚠️ **CRITICAL GAP** - Main repo lacks self-hosting documentation

---

4.2 Architecture Documentation

atom-upstream

• ✅ Self-hosting architecture diagrams
• ✅ Single-tenant data flow
• ✅ Docker Compose architecture
• ✅ Security model (encryption, secrets)

Main Repo

• ✅ Multi-tenant architecture
• ✅ Brain systems documentation
• ✅ Tenant isolation patterns
• ✅ SaaS data flow

**Gap Analysis:** ✅ **Complementary** - Different architectures documented

---

5. Integration Support

5.1 Integration Count

**Total:** 46+ (atom-upstream) vs ~10 (main repo)

**Gap Analysis:** ⚠️ **SIGNIFICANT GAP** - Main repo missing 35+ integrations

---

5.2 Integration Implementation

atom-upstream

**OAuth System:**

• Complete OAuth flow for all providers
• Callback URL configuration
• Token encryption at rest
• Per-user credential storage
• Refresh token handling

**Local-Only Mode:**

ATOM_LOCAL_ONLY=true  # Blocks all cloud services

**Privacy Features:**

• Local services continue working (Hue, Home Assistant, FFmpeg)
• Cloud services blocked (Spotify, Notion)
• All data stays local

Main Repo

**OAuth System:**

• Basic OAuth for CRM and communication
• Tenant-scoped credentials
• Stripe billing integration

**Missing:**

• ❌ Smart home integrations
• ❌ Media integrations
• ❌ Project management tools
• ❌ Most DevOps tools
• ❌ Local-only mode

**Gap Analysis:** ⚠️ **SIGNIFICANT GAP** - Integration coverage is 20% of upstream

---

6. Monitoring & Operations

6.1 Monitoring Stack

atom-upstream

**Personal Edition:**

• Basic logging
• Health checks
• Service status monitoring

**Enterprise Edition:**

• Prometheus metrics
• Grafana dashboards
• Alert configuration
• Performance monitoring

**Scripts:**

• scripts/monitor_production.sh
• scripts/backup.sh
• Health check endpoints on all services

Main Repo

**Current:**

• ATOM Cloud monitoring (native)
• Basic health endpoints
• Error logging

**Missing:**

• ❌ Prometheus setup
• ❌ Grafana dashboards
• ❌ Alert configuration
• ❌ Backup automation
• ❌ Performance monitoring tools

**Gap Analysis:** ⚠️ **SIGNIFICANT GAP** - Main repo relies on ATOM Cloud managed services

---

6.2 Backup & Recovery

atom-upstream

**Backup Script:**

./production/backup.sh
# Creates timestamped SQL dumps
# 7-day retention policy
# Automated via cron

**Recovery:**

• Documented restore procedures
• Volume persistence
• Database migration scripts

Main Repo

**Current:**

• ATOM Cloud automatic backups (managed)
• No manual backup scripts
• No documented restore procedures

**Gap Analysis:** ⚠️ **GAP** - Main repo lacks self-hosted backup tooling

---

7. Testing & Quality

7.1 Test Coverage

atom-upstream

**Test Suites:**

• Unit tests (Python, TypeScript)
• Integration tests
• E2E tests (Playwright)
• Property-based tests
• Cross-platform tests

**Coverage Reports:**

• HTML coverage reports
• XML coverage reports
• Final test reports

**Scripts:**

• docker-compose-e2e.yml
• docker-compose-e2e-ui.yml
• playwright.config.ts

Main Repo

**Test Suites:**

• Unit tests (partial)
• Integration tests (partial)
• E2E tests (minimal)

**Missing:**

• ❌ Comprehensive E2E suite
• ❌ Property-based tests
• ❌ Cross-platform tests
• ❌ Coverage reports

**Gap Analysis:** ⚠️ **GAP** - Main repo has reduced test coverage

---

8. CLI & Developer Tools

8.1 Command-Line Interface

atom-upstream

**Atom CLI:**

atom init              # Initialize installation
atom start            # Start services
atom daemon           # Background mode
atom status          # Check status
atom stop            # Stop services
atom enable enterprise  # Upgrade edition

**Installation:**

pip install atom-os

Main Repo

**CLI:**

• ❌ No dedicated CLI
• Manual setup required
• No automation commands

**Gap Analysis:** ⚠️ **GAP** - Main repo lacks CLI tooling

---

8.2 Development Experience

atom-upstream

**Features:**

• Hot reload (backend and frontend)
• SQLite for rapid development
• Local-only mode for privacy
• Comprehensive .env templates
• One-command setup

**Developer Tools:**

• Pre-commit hooks
• Linting configuration
• Type checking
• Test automation

Main Repo

**Features:**

• ATOM Cloud development deployment
• Manual environment setup
• SaaS-focused configuration

**Missing:**

• ❌ Hot reload setup
• ❌ Local development shortcuts
• ❌ Comprehensive .env templates
• ❌ One-command setup

**Gap Analysis:** ⚠️ **GAP** - Main repo has poorer DX for self-hosting

---

9. Security Comparison

9.1 Security Features

atom-upstream

**Encryption:**

• Fernet symmetric encryption
• BYOK (Bring Your Own Key)
• Per-user credential encryption
• Secrets migration (plaintext → encrypted)

**Authentication:**

• JWT tokens (24-hour expiry)
• OAuth2 (Google, Okta, Auth0, SAML)
• Mobile biometric support
• Internal service tokens

**Audit:**

• Audit logging (all credential access)
• 90-day retention
• Security event tracking

**Security Rating:** A- (documented audit)

Main Repo

**Encryption:**

• Fernet encryption (inherited)
• Tenant-scoped secrets

**Authentication:**

• JWT with tenant context
• Multi-tenant RBAC
• 40+ granular permissions

**Audit:**

• Tenant-scoped audit logs
• Threat level assessment

**Missing:**

• ❌ Security audit documentation
• ❌ Data protection guide
• ❌ Encryption key management guide

**Gap Analysis:** ⚠️ **DOCUMENTATION GAP** - Security features exist but undocumented

---

10. Gap Summary & Recommendations

10.1 Critical Gaps (Must Fix)

10.2 Significant Gaps (Should Fix)

10.3 Intentional Gaps (Acceptable)

---

11. Action Plan

Phase 1: Critical Self-Hosting Support (Week 1-2)

**Goal:** Enable basic self-hosting of main repo

1. **Create Self-Hosting Documentation**

• Installation guide (Docker, pip, native)
• Environment configuration guide
• Deployment checklist
• Backup/recovery procedures

1. **Enhance Docker Compose**

• Add frontend service
• Add browser automation
• Add health checks
• Add volume persistence
• Create development and production variants

1. **Create Deployment Scripts**

• Production setup automation
• Backup automation
• Monitoring setup
• One-command start

1. **Expand Environment Configuration**

• Document all 46+ integrations
• Create comprehensive .env.example
• Add AI provider credentials
• Add integration templates

Phase 2: Integration Parity (Week 3-4)

**Goal:** Restore integration coverage

1. **Port Missing Integrations**

• Smart home (Hue, Home Assistant, Sonos)
• Media (Spotify, YouTube)
• Project management (GitHub, Jira, Notion, etc.)
• Storage providers (Dropbox, Box, etc.)
• DevOps tools (PagerDuty, Datadog, etc.)

1. **Implement Local-Only Mode**

• Privacy-focused deployment
• Block cloud services when needed
• Maintain local service functionality

1. **Update Documentation**

• Integration setup guides
• OAuth configuration
• Troubleshooting guides

Phase 3: Monitoring & Operations (Week 5-6)

**Goal:** Production-ready operations

1. **Add Monitoring Stack**

• Prometheus setup
• Grafana dashboards
• Alert configuration
• Performance monitoring

1. **Enhance Testing**

• E2E test suite
• Property-based tests
• Coverage reports
• Cross-platform tests

1. **Create CLI Tools**

• atom init command
• atom start/stop commands
• atom status command
• atom daemon mode

Phase 4: Security & Quality (Week 7-8)

**Goal:** Enterprise-grade security

1. **Security Documentation**

• Security overview
• Data protection guide
• Encryption key management
• Audit logging guide

1. **Quality Improvements**

• Code style enforcement
• Type checking
• Linting automation
• Pre-commit hooks

1. **Developer Experience**

• Hot reload setup
• Local development shortcuts
• Comprehensive templates
• Troubleshooting guides

---

12. Conclusion

Current State

The **main repository** has excellent **SaaS/multi-tenant features** but lacks comprehensive **self-hosting support** that exists in the **atom-upstream** submodule.

Key Statistics

• **Self-Hosting Options:** 5 (upstream) vs 1 (main)
• **Integration Coverage:** 46+ (upstream) vs ~10 (main) - **78% gap**
• **Documentation:** 654 lines (upstream) vs ~200 lines (main) - **70% gap**
• **Deployment Scripts:** 8 (upstream) vs 2 (main) - **75% gap**
• **Environment Variables:** 323 lines (upstream) vs 237 lines (main) - **27% gap**

Recommendations

1. **Immediate (P0):** Port self-hosting documentation, Docker configs, and deployment scripts from upstream
2. **Short-term (P1):** Restore integration coverage and add monitoring stack
3. **Medium-term (P2):** Improve testing, CLI tooling, and developer experience
4. **Long-term:** Maintain parallel documentation for SaaS and self-hosted deployments

Strategic Decision

**Question:** Should the main repository support both SaaS and self-hosted deployments?

**Options:**

1. **SaaS-Only Focus:** Keep main repo SaaS-focused, direct self-hosting users to upstream
2. **Dual Support:** Maintain both SaaS and self-hosted capabilities in main repo
3. **Merge Upstream:** Fully integrate upstream self-hosting into main repo

**Recommended:** **Option 2 (Dual Support)** - Maintain flexibility for different deployment models while sharing core codebase.

---

**Appendix A:** File Comparison Matrix

**Appendix B:** Integration Provider List

**Appendix C:** Environment Variable Reference

**Appendix D:** Deployment Script Examples

---

**Document Version:** 1.0

**Last Updated:** March 31, 2026

**Author:** Gap Analysis Agent

**Review Status:** Pending